<!doctype linuxdoc system>

<article>

<title> README for XFree86 3.1.2 on LynxOS
<author>Thomas Mueller
<date>14 November 1995
<toc>

<sect>What and Where is XFree86?<p>
XFree86 is a port of X11R6 that supports several versions of Intel-
based Unix.  It is derived from X386 1.2, which was the X server
distributed with X11R5.  This release consists of many new features
and performance improvements as well as many bug fixes.  The release
is available as source patches against the X Consortium X11R6 code, as
well as binary distributions for many architectures.

See the Copyright Notice in <url url="COPYRIGHT.html" name="COPYRIGHT">.

The sources for XFree86 are available by anonymous ftp from:

<url url="ftp://ftp.XFree86.org/pub/XFree86/current"
name="ftp.XFree86.org:/pub/XFree86/current">
 
The XFree86 LynxOS port was developed using `LynxOS AT 2.3.0 080695-A FCS'.

XFree86 currently supports only LynxOS on the AT platform. The
library and client part of XFree86 could although compile without
problems on other LynxOS platforms (e.g. SPARC, Motorola-68K or
PowerPC).

<sect>Bug Reports for This Document<p>
Send email to <it>tm@systrix.de</it> (Thomas Mueller) or
<it>XFree86@XFree86.org</it> if you have comments or suggestions about
this file and we'll revise it.

<sect>Compiling the XFree86 Distribution<p>
<sect1>Disk space requirements<p>
Currently there is no support for shared libraries in the LynxOS
XFree86 port. A complete binary installation along with manual pages
will require approximately 70-90 MBytes of disk space. To compile
the system you will need at least 230 MBytes of free disk space.

<sect1>Changes to system environment<p>
Before compiling the XFree86 distribution you will have to make a
few little adjustments to your system:

  <descrip>
  <tag>LynxOS AT 2.3 </tag>
  <itemize>
  <item> Use the CYGNUS GNU-C Compiler to build XFree86. With LynxOS 2.3.0 
    you must execute the shell script <tt>/CYGNUS.bash</tt> to apply the
    necessary changes to your environment.
  <item> Create a shell script named /lib/cpp as follows:
  <tscreen><verb>
    #!/bin/sh
    /cygnus/94q4-lynxos-x86/lib/gcc-lib/i386-lynx/2.6-94q4/cpp \
	      -traditional "$@"
  </verb></tscreen>
    It is possible that future releases use a different path for
    the CYGNUS compiler support programs. You may use
  <tscreen><verb>
	gcc -v
  </verb></tscreen>
    to find out the correct path. Set the file mode of /lib/cpp with
  <tscreen><verb>
        # chown root /lib/cpp
	# chmod 755 /lib/cpp
  </verb></tscreen>
  </itemize>
  <tag>LynxOS AT 2.2.1</tag>
  <itemize>
  <item> Create a shell script named /lib/cpp as follows:
  <tscreen><verb>
    #!/bin/sh
    /usr/local/lib/gcc-cpp -traditional "$@"
  </verb></tscreen>
  <item> The loader /bin/ld of LynxOS 2.2.1 does not support the -L option
    which is heavily used by X11R6 makefiles. To work around this
    problem you must install a small wrapper program which replaces
    the original /bin/ld program. Use the following steps to install
    it:
  <tscreen><verb>
      # cd xc/programs/Xserver/hw/xfree/etc
      # cc -o ld ld-wrapper.c
      # mv /bin/ld /bin/ld.org
      # mv ld /bin/ld
      # chmod 511 /bin/ld
      # chown root /bin/ld
  </verb></tscreen>
  <item> Modify system header files as follows:
  <descrip>
    <tag><tt>/usr/include/uio.h</tt></tag> surrounded by
     <tscreen><verb>
          #ifndef _UIO_H
          #define _UIO_H
          ...
          #endif
     </verb></tscreen>
    <tag><tt>/usr/include/utmp.h</tt></tag> surrounded by
     <tscreen><verb>
          #ifndef _UTMP_H
          #define _UTMP_H
          ...
          #endif
     </verb></tscreen>
    <tag><tt>/usr/include/unistd.h</tt></tag> add
     <tscreen><verb>
          extern int read();
     </verb></tscreen>
    </descrip>
  </itemize>
  </descrip>

<sect1> make World<p>

  Before you start compilation you must edit <tt>xc/config/cf/lynx.cf</tt> to
  match your operating system version. Change the definitions of
  OSMajorVersion, OSMinorVersion and OSTeenyVersion accordingly.

  For LynxOS 2.3.0 the OptimizedCDebugFlags is set to `-O -m486'. Higher
  optimization levels are not enabled by default to work around a bug
  in -O2 for GCC v2.6.x.
  You might try enabling -O2 if your compiler does not have this bug,
  but if the session manager xsm hangs on startup it would be a good 
  idea to switch back to -O.

  You may now issue a

  <tscreen><verb>
     make World
  </verb></tscreen>

  to compile XFree86. After a few hours (and hopefully a successful
  build of the XFree86 system) you can install the software using

  <tscreen><verb>
     make install
  </verb></tscreen>

  You must be logged in as super-user (root) when you invoke `make
  install'.  Be sure to set your environment to use the same compiler
  (LynxOS 2.3.0, CYGNUS GNU-C) as you did during the `make World'. To
  install the LinkKit use

  <tscreen><verb>
     make install.linkkit
  </verb></tscreen>

  With LynxOS 2.2.1 programs will not be stripped during
  installation. This is due to a problem with the strip program which
  shows up when installing across file system boundaries.

  Refer to section 5 for manual page installation.

<sect>Running XFree86<p>
<sect1>System requirements<p>
  A minimum of 8MB of memory is required to run X. If you want to run
  real-world applications you should think of upgrading to 16MB. If
  you plan to develop software under X take 32MB into consideration.

<sect1>System tuning<p>
<sect2>Tunable parameters<p>

  To run XFree86 reasonably you must adjust a few system parameters in
  <tt>/usr/include/param.h</tt>:

<verb>
  Tunable					        Old	New
  USR_NFDS	number of open files per process	 20	 64
  NPROC		number of tasks				 50	150
  NFILES	number of open files in system		100	250
  NINODES	number of incore inodes			(same value as NFILES)
  QUANTUM	clock ticks until preemption		 64      20
  CACHEBLKS	number of cache memory blocks		202	 >= 4096
</verb>

  The new values are those suggested by the LynxOS documentation for
  their X Window package.

<sect2>Increase number of ptys<p>

  You should also increase the number of ptys to be able run a couple
  more xterms. You may replace <tt>/sys/lynx.os/pty.cfg</tt> with
  <tt>/usr/X11R6/lib/X11/etc/pty.cfg</tt>.

<sect2>Kernel build<p>

  If you plan to use PS/2 or Bus mice refer to the following section
  before rebuilding the kernel, if not, you should rebuild the kernel
  now: 

  <tscreen><verb>
     # cd /sys/lynx.os
     # make install
     # reboot -N
  </verb></tscreen>

<sect1>Bus mouse drivers<p>

  LynxOS does not provide device drivers for Bus or PS/2 mice.
  <tt>/usr/X11R6/lib/X11/etc/BM-Lynx.shar</tt> contains a port 
  of the Linux drivers for those devices. To install the drivers
  unpack the tar 

  <tscreen><verb>
    # cd /
    # bash /usr/X11R6/lib/X11/etc/BM-Lynx.shar
  </verb></tscreen>

  and follow the notes in <tt>/BMOUSE.Readme</tt> for further installation and
  configuration notes.
   
<sect1> ATC console driver and VT switching<p>

  The XFree86 servers will only run with the default LynxOS console
  driver, sorry for those of you who use the alternative vdt console
  driver. Currently there is no support for virtual terminal switching
  once the server has started.

  You will need a free console which the X server will use for
  keyboard input. You must disable login on at least one of the four
  virtual terminals in /etc/ttys, e.g. /dev/atc3:

  <tscreen>
    change
  <verb>
       /dev/atc3:1:default:vt100at:/bin/login
  </verb>
    to
  <verb>
       /dev/atc3:0:default:vt100at:/bin/login
                 ^
  </verb></tscreen>

<sect1>X Server debug diagnostics output and other VT peculiarities<p>

  The XFree86 X servers will produce a lot of diagnostics output on
  stderr during startup. This output will be lost after the server
  reached a certain point in its console initialization process. You
  should redirect stdout and stderr if you want to analyze the
  diagnostics produced by the server.

  When the X server is running output made to other consoles will be
  lost. After server shutdown the screen contents of other consoles
  may be inconsistent with what one would expect (i.e. random).

<sect>Installing XFree86 manual pages<p>

  LynxOS uses cat-able manual pages, and because a doc preparation
  system is definitely not a vital component of a real-time operating
  system you must first install groff-1.09. With LynxOS 2.3.0 it
  compiles right out of the box (or better tar archive).

  XFree86 manual pages may be installed using

  <tscreen><verb>
     make install.man
  </verb></tscreen>

  The index and whatis database for the XFree86 manual pages will be
  created automatically. If you have already a whatis database or
  index file in the destination directories you should perform a
  sort/uniq operation to remove duplicate entries:

  <tscreen><verb>
     for i in 1 3 5
     do
       rm -f /tmp/tmpfile
       sort /usr/X11R6/man/cat$i/LIST$i | uniq > /tmp/tmpfile
       mv /tmp/tmpfile /usr/X11R6/man/cat$i/LIST$i
     done
     sort /usr/X11R6/man/whatis | uniq > /tmp/tmpfile
     mv /tmp/tmpfile /usr/X11R6/man/whatis
  </verb></tscreen>
  
  With LynxOS 2.3.0 you should include <tt>/usr/X11R6/man</tt> in the MANPATH
  environment variable.

  <tscreen>
      bash:   <tt>MANPATH=&dollar;MANPATH:/usr/X11R6/man</tt>
  </tscreen>

  The /bin/man command of LynxOS 2.2.1 does not support the MANPATH
  environment variable properly. The XFree86 manual pages must be
  copied (or linked) to the standard manual page locations
  (<tt>/usr/man/catx</tt>) in  order to be read the man command:

  <tscreen><verb>
      for i in 1 3 5
      do
        ln -s /usr/X11R6/man/cat$i/*.* /usr/man/cat$i
	cat /usr/X11R6/man/cat$i/LIST$i >> /usr/man/cat$i/LIST$i
	sort -o /usr/man/cat$i/LIST$i /usr/man/cat$i/LIST$i
	cat /usr/X11R6/man/cat$i/whatis$i >> /usr/man/whatis
      done
  </verb></tscreen>

<sect>Using XFree86 with Motif<p>

  The Motif libraries shipped with LynxOS AT 2.3.0 can be used with
  the XFree86 libraries. Follow the steps outlined below after
  you have installed XFree86 and LynxOS Motif on your system.

<sect1>Copy Motif files<p>

  You must create symbolic links for the Motif libraries and 
  utilities in the /usr/X11R6 directory tree.
  <tscreen><verb>
      ln -s /usr/bin/X11/uil /usr/X11R6/bin
      ln -s /usr/lib/libUil.a /usr/X11R6/lib
      ln -s /usr/lib/libMrm.a /usr/X11R6/lib
      ln -s /usr/lib/X11/uid /usr/X11R6/lib/X11
      ln -s /usr/include/Xm /usr/X11R6/include
      ln -s /usr/include/Mrm /usr/X11R6/include
      ln -s /usr/include/uil /usr/X11R6/include
  </verb></tscreen>

  The Motif imake-configuration files are part of the LynxOS X Window
  package. They must be copied to the /usr/X11R6 directory tree.
  <tscreen><verb>
      cp /usr/lib/X11/config/Motif.* /usr/X11R6/lib/X11/config
  </verb></tscreen>

<sect1>Motif library patch<p>

  The XFree86 libraries are compiled with the -mposix compiler option
  while the Motif libraries shipped with LynxOS AT 2.3.0 are not. This
  incompatibility will cause Motif XmFileSelection widgets to be linked 
  with the wrong (i.e. POSIX) directory routines. To circumvent this 
  problem apply the following patch to the library:
  <tscreen><verb>
      cp /usr/lib/libXm.a /usr/X11R6/lib
      ar x /usr/X11R6/lib/libXm.a Xmos.o
      ar x /lib/libc.a directory.s.o
      ld -r -o x.o Xmos.o directory.s.o
      mv x.o Xmos.o
      ar r /usr/X11R6/lib/libXm.a Xmos.o
  </verb></tscreen>
  
<sect1>X11R6 config file patch<p>

  Edit <tt>/usr/X11R6/lib/X11/config/lynx.cf</tt> and change the definition
  of <tt>HasMotif</tt>
  <tscreen>
    from
  <verb>
       #define HasMotif    NO
  </verb>
    to
  <verb>
       #define HasMotif    YES
  </verb></tscreen>

<sect1>Motif config file patch<p>

  The file <tt>Motif.tmpl</tt> shipped with LynxOS Motif must be modified
  to work with XFree86. In every reference to <tt>UnsharedLibReferences</tt>
  the first argument must be changed
  <tscreen>
    from
  <verb>
       UnsharedLibReferences(<Something>LIB, Arg2, Arg3)
  </verb>
    to
  <verb>
       UnsharedLibReferences(<Something>, Arg2, Arg3)
  </verb></tscreen>
  Be sure to apply the change to the file copied to
  <tt>/usr/X11R6/lib/X11/config</tt>.

<verb>
$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/LynxOS.sgml,v 3.4 1995/12/28 03:49:29 dawes Exp $





$XConsortium: LynxOS.sgml /main/4 1995/12/29 15:58:36 kaleb $
</verb>
</article>
